Inside Macintosh: Programming With the Text Encoding Conversion Manager /

Chapter 3 - Text Encoding Converter Reference / Text Encoding Converter Functions

Converting Text Between Encodings /

TECConvertText

Converts a stream of text from a source encoding to a destination encoding.

pascal OSStatus TECConvertText(
                     TECObjectRef encodingConverter,
                     ConstTextPtr inputBuffer,
                     ByteCount inputBufferLength,
                     ByteCount *actualInputLength,
                     TextPtr outputBuffer,
                     ByteCount outputBufferLength,
                     ByteCount *actualOutputLength);

encodingConverter

The reference to the text encoding converter object to be used for the conversion.This can be a reference returned by the function TECCreateConverter (page 91) or TECCreateConverterFromPath (page 92).

inputBuffer

The stream of text to be converted.

inputBufferLength

The length in bytes of the stream of text specified in the inputBuffer parameter. A byte is currently defined as a value of type UInt8 or unsigned char.

actualInputLength

A pointer to a value of type ByteCount. On output, this value is the number of source text bytes from the input buffer that TECConvertText converted.

outputBuffer

A pointer to a buffer for a byte stream. On output, this buffer holds the converted text.

outputBufferLength

The length in bytes of the buffer provided by the outputBuffer parameter.

actualOutputLength

A pointer to a value of type ByteCount. On output this value is the number of bytes of converted text returned in the buffer specified by the outputBuffer parameter.

function result

A result code. See "Text Encoding Conversion Manager Result Codes" (page 42) for a list of possible values. If there is not enough memory available for TECConvertText to convert the text when allocating internal buffers, the function returns the appropriate Memory Manager result code.

DISCUSSION

The TECConvertText function converts a buffer of text according to information contained in the converter object. The converter object specifies the source encoding, destination encoding, and any intermediate encodings required for conversion. The function returns the text in the output buffer that you provide.

In allocating an output buffer, a good rule of thumb is larger is better, basing your estimate on the byte requirements of the destination encoding. You should always allocate a buffer at least 32 bytes long. For the function to return successfully, the output buffer you allocate must be large enough to accommodate at least part of the converted text. Then, if the function cannot convert all of the text, it executes successfully, returns the portion of the text it converted, and returns the number of source bytes it removed from input in the actualInputLength parameter. You can use this number to identify the next byte to be taken and to determine how many bytes remain. To convert the remaining text, you simply call the function again with the remaining text and a new output buffer.

If the output buffer you allocate is too small to accommodate any of the converted text, the function fails. For example, if the destination encoding requires additional bytes in addition to the actual text (for instance, an escape sequence preceding the converted text), your buffer must be large enough to accommodate both.

IMPORTANT

If the destination encoding is a character encoding scheme--such as ISO-2022-JP, which begins in ASCII and switches to other coded character sets through limited combinations of escape sequences--then you need to allocate enough space to accommodate escape sequences that signal switches. ISO-2022-JP requires 3 to 5 bytes for an escape sequence preceding the 1-byte or 2-byte character it introduces. If you allocate a buffer that is less than 5 bytes, the TECConvertText function could fail, depending on the text being converted.

To make sure that you receive all of the converted text, you should call the function TECFlushText (page 97) when you are finished converting all the text in a particular text stream.